JavaScript

A5.ListBoxsetOrder Method

Syntax

A5.ListBox.setOrder(order)

Arguments

orderbooleanfunctionobjectarray: The order to sort the list data in.

Description

Order the rows in the list.

Discussion

When a function can be passed in to sort the list data, the function will be called with two rows of the list. The function must return 1 if the first row passed in should be sorted above then the second, -1 if the opposite and 0 if they are equivalent.

A single column can be sorted by passing in an object with a property with the same name as the column to sort, and a number of 1 for ascending and -1 for descending .

Multiple columns can be sort sequentially by passing in an array of arrays. The first entry in each child array will be the name of the column to sort and then second entry a number of 1 for ascending and -1 for descending .

If the columns data needs to be formatted before comparing them, the column name can have the formatting data append following a ":". There are five types of formats that can be applied: "number", "boolean", "date", "first" and "length". Both "number" and "boolean" will convert the column data to the given type before comparing them. The "date" format requires the date format to be used for parsing the string to be passed in following a second ":". The "first" format expects the number of starting characters to compare to be passed in following a second ":". The "length" format will compare the lengths of the column data instead of the values.

Example

// To get a pointer to the A5.ListBox class see {dialog.object}.getControl
// assume lObj is a pointer to an instance of the A5.ListBox class
lObj.setOrder({'DOB:date:MM/dd/yyyy': 1}); //  sort the "DOB" column in ascending order as a date with the format "MM/dd/yyyy"
lObj.setOrder([['LastName:first:1',1],['Age',-1]]); // sort on the first character of the "LastName" column in ascending order, and then sort on the "Age" column in descending  order
lObj.setOrder(false); // clear the sorting

Example: Setting the Order for a List Control

The example below demonstrates setting the order for a List Control in a UX Component.

var listObj = {dialog.object}.getControl('LIST1');

//Sort on the first character of the Lastname fields
listObj.setOrder({'Country:first:1' : 1});

//Sort on the DateOfBirth fields (you must specify the date format)
listObj.setOrder({'DateOfBirty:date:MM-dd-yyyy' : 1});

//Un-sort the List (to get back to its natural order)
listObj.setOrder(false);

//Sort on Country (ascending) and then within Country, by City (descending)
var sortObj = [ ['Country',1], ['City' , -1]];
listObj.setOrder(sortObj);

//the value of 1 is assumed if omitted, so the following is same as above example
var sortObj = [ 'Country', ['City' , -1]];
listObj.setOrder(sortObj);

If the rows in the list are strings not objects, then a number with the value of 1 or -1 should be passed in. Since there are no columns in the list, the object ordering cannot be done.